#define _POSIX_C_SOURCE 200809L
/**
 * @file protocol_connection.c
 * @brief 104协议连接管理实现
 * @details 本文件实现了104协议的连接管理功能，包括STARTDT、STOPDT、TESTFR
 *          等连接控制功能。实现完整的104协议连接建立、维护和释放逻辑。
 * 
 *          主要功能包括：
 *          - 连接状态管理：管理连接的生命周期状态
 *          - STARTDT/STOPDT控制：处理数据传输启动和停止
 *          - TESTFR心跳：维护连接活跃性
 *          - 超时管理：处理各种超时情况
 *          - 统计信息：记录连接相关的统计数据
 *          - 回调机制：支持状态变化和事件通知
 * 
 * @author 电网协议开发团队
 * @date 2024
 * @version 1.0
 * 
 * @note 本模块是104协议栈的核心组件，负责管理协议连接的生命周期
 * @warning 所有函数都是线程安全的，使用互斥锁保护共享数据
 * @see protocol_connection.h
 * @see protocol_types.h
 * @see constants.h
 */

#include "../include/protocol_connection.h"
#include "../../protocol/apdu/include/apdu_assembler.h"
#include "../../protocol/apdu/include/apdu_parser.h"
#include "../../common/types/include/constants.h"
#include "../../../../../common/logs/include/logger.h"
#include <stdlib.h>
#include <unistd.h>
#include <string.h>
#include <pthread.h>
#include <sys/time.h>

// 定义模块名称
#define LOG_MODULE_NAME "PROTOCOL_CONNECTION"

/* ==================== 前向声明 ==================== */

/* ==================== 连接管理器私有数据结构 ==================== */

/**
 * @brief 连接管理器私有数据结构
 * @details 该结构体包含了连接管理器的所有私有数据，包括配置信息、
 *          状态管理、统计信息、回调函数、线程管理和超时控制等。
 *          所有数据都通过互斥锁进行线程安全保护。
 */
typedef struct {
    /* ==================== 配置和状态 ==================== */
    connection_config_t config;           /* 连接配置参数，包括超时时间、重试次数等 */
    connection_state_t current_state;     /* 当前连接状态：断开/连接中/已连接/断开中/错误 */
    connection_stats_t stats;             /* 连接统计信息，记录各种操作次数和状态 */
    
    /* ==================== 回调函数管理 ==================== */
    connection_state_callback_t state_callback;  /* 状态变化回调函数指针 */
    void* state_user_data;                       /* 状态回调用户数据指针 */
    connection_event_callback_t event_callback;  /* 事件处理回调函数指针 */
    void* event_user_data;                       /* 事件回调用户数据指针 */
    connection_send_callback_t send_callback;    /* APDU发送回调函数指针 */
    void* send_user_data;                         /* 发送回调用户数据指针 */
    
    /* ==================== 线程管理 ==================== */
    pthread_t heartbeat_thread;           /* 心跳线程句柄，用于定期发送TESTFR */
    bool thread_running;                  /* 心跳线程运行标志，控制线程生命周期 */
    pthread_mutex_t mutex;                /* 互斥锁，保护共享数据的线程安全 */
    
    /* ==================== 超时和活动管理 ==================== */
    struct timeval last_activity;         /* 最后活动时间戳，用于心跳间隔计算 */
    bool waiting_for_response;            /* 等待响应标志，表示是否在等待对方确认 */
    connection_event_t pending_event;     /* 待处理事件类型，记录当前等待的事件 */
    
    /* ==================== 运行控制 ==================== */
    bool running;                         /* 管理器运行标志，控制整个管理器的生命周期 */
} protocol_connection_private_t;

/* ==================== 前向声明 ==================== */

static void protocol_connection_change_state(protocol_connection_private_t* private_data, 
                                           connection_state_t new_state);
static void protocol_connection_send_startdt_confirm(protocol_connection_private_t* private_data);
static void protocol_connection_send_stopdt_confirm(protocol_connection_private_t* private_data);
static void protocol_connection_send_testfr_confirm(protocol_connection_private_t* private_data);
static void protocol_connection_start_heartbeat(protocol_connection_private_t* private_data);
static void* protocol_connection_heartbeat_thread(void* arg);

/* ==================== 连接管理函数实现 ==================== */

/**
 * @brief 创建连接管理器
 * @details 创建并初始化一个新的104协议连接管理器实例。该函数会分配内存、
 *          验证配置参数、初始化内部状态和互斥锁，并设置初始的连接状态。
 *          连接管理器负责处理STARTDT、STOPDT、TESTFR等连接控制功能。
 * 
 * @param config 连接配置参数指针，不能为NULL
 *               - startdt_timeout: STARTDT超时时间(ms)
 *               - stopdt_timeout: STOPDT超时时间(ms) 
 *               - testfr_timeout: TESTFR超时时间(ms)
 *               - heartbeat_interval: 心跳间隔(ms)
 *               - max_retry_count: 最大重试次数
 *               - auto_heartbeat: 是否自动心跳
 *               - auto_reconnect: 是否自动重连
 * 
 * @return 连接管理器句柄，成功返回有效句柄，失败返回NULL
 * 
 * @note 创建的连接管理器需要调用protocol_connection_destroy()释放资源
 * @warning 配置参数必须通过protocol_connection_validate_config()验证
 * @see protocol_connection_destroy
 * @see protocol_connection_validate_config
 */
protocol_connection_handle_t protocol_connection_create(const connection_config_t* config) {
    LOG_DEBUG(LOG_MODULE_NAME, "函数入口: protocol_connection_create, config=%p", config);
    
    // 参数有效性检查
    if (config == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "连接配置参数为空指针");
        return NULL;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "开始创建连接管理器，配置参数: STARTDT超时=%dms, STOPDT超时=%dms, TESTFR超时=%dms", 
             config->startdt_timeout, config->stopdt_timeout, config->testfr_timeout);
    
    // 验证配置参数的有效性
    protocol_error_t validation_result = protocol_connection_validate_config(config);
    if (validation_result != PROTOCOL_SUCCESS) {
        LOG_ERROR(LOG_MODULE_NAME, "连接配置验证失败，错误码: %d", validation_result);
        return NULL;
    }
    
    LOG_DEBUG(LOG_MODULE_NAME, "配置验证通过，开始分配内存");
    
    // 分配连接管理器私有数据结构内存
    protocol_connection_private_t* private_data = 
        (protocol_connection_private_t*)malloc(sizeof(protocol_connection_private_t));
    if (private_data == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "内存分配失败，无法创建连接管理器");
        return NULL;
    }
    
    LOG_DEBUG(LOG_MODULE_NAME, "内存分配成功，地址: %p，大小: %zu字节", 
              private_data, sizeof(protocol_connection_private_t));
    
    // 初始化私有数据结构
    memset(private_data, 0, sizeof(protocol_connection_private_t));
    
    // 复制配置参数到私有数据结构
    memcpy(&private_data->config, config, sizeof(connection_config_t));
    LOG_DEBUG(LOG_MODULE_NAME, "配置参数复制完成");
    
    // 初始化连接状态
    private_data->current_state = CONNECTION_STATE_DISCONNECTED;
    private_data->waiting_for_response = false;
    private_data->running = false;
    private_data->thread_running = false;
    LOG_DEBUG(LOG_MODULE_NAME, "连接状态初始化完成，初始状态: DISCONNECTED");
    
    // 初始化互斥锁
    int mutex_result = pthread_mutex_init(&private_data->mutex, NULL);
    if (mutex_result != 0) {
        LOG_ERROR(LOG_MODULE_NAME, "互斥锁初始化失败，错误码: %d", mutex_result);
        free(private_data);
        return NULL;
    }
    LOG_DEBUG(LOG_MODULE_NAME, "互斥锁初始化成功");
    
    // 记录连接管理器创建时间
    gettimeofday(&private_data->last_activity, NULL);
    LOG_DEBUG(LOG_MODULE_NAME, "创建时间记录完成: %ld.%06ld", 
              private_data->last_activity.tv_sec, private_data->last_activity.tv_usec);
    
    LOG_INFO(LOG_MODULE_NAME, "连接管理器创建成功，句柄: %p，状态: DISCONNECTED", 
             (protocol_connection_handle_t)private_data);
    
    return (protocol_connection_handle_t)private_data;
}

/**
 * @brief 销毁连接管理器
 * @details 销毁连接管理器实例，清理所有相关资源。该函数会先停止连接管理器
 *          的运行，然后销毁互斥锁，最后释放内存。这是protocol_connection_create()
 *          的配对函数，用于释放连接管理器占用的所有资源。
 * 
 * @param handle 连接管理器句柄，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 销毁成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 句柄为空指针
 * 
 * @note 调用此函数后，连接管理器句柄将变为无效，不应再使用
 * @warning 此函数会强制停止所有连接活动，请确保在合适的时机调用
 * @see protocol_connection_create
 */
protocol_error_t protocol_connection_destroy(protocol_connection_handle_t handle) {
    LOG_DEBUG(LOG_MODULE_NAME, "函数入口: protocol_connection_destroy, handle=%p", handle);
    
    // 参数有效性检查
    if (handle == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "连接管理器句柄为空指针");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    protocol_connection_private_t* private_data = (protocol_connection_private_t*)handle;
    LOG_INFO(LOG_MODULE_NAME, "开始销毁连接管理器，句柄: %p，当前状态: %s", 
             handle, protocol_connection_get_state_name(private_data->current_state));
    
    // 停止连接管理器，清理所有活动
    LOG_DEBUG(LOG_MODULE_NAME, "停止连接管理器");
    protocol_error_t stop_result = protocol_connection_stop(handle);
    if (stop_result != PROTOCOL_SUCCESS) {
        LOG_WARN(LOG_MODULE_NAME, "停止连接管理器时发生错误，错误码: %d", stop_result);
    }
    
    // 销毁互斥锁
    LOG_DEBUG(LOG_MODULE_NAME, "销毁互斥锁");
    int mutex_result = pthread_mutex_destroy(&private_data->mutex);
    if (mutex_result != 0) {
        LOG_ERROR(LOG_MODULE_NAME, "互斥锁销毁失败，错误码: %d", mutex_result);
    } else {
        LOG_DEBUG(LOG_MODULE_NAME, "互斥锁销毁成功");
    }
    
    // 释放内存
    LOG_DEBUG(LOG_MODULE_NAME, "释放连接管理器内存，地址: %p", private_data);
    free(private_data);
    
    LOG_INFO(LOG_MODULE_NAME, "连接管理器销毁完成，句柄: %p", handle);
    
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 启动连接
 * @details 启动104协议连接，发送STARTDT请求开始数据传输。该函数会检查当前连接状态，
 *          只有在断开状态下才能启动连接。启动过程包括状态转换、构建STARTDT APDU、
 *          发送请求并设置等待响应标志。如果配置了自动心跳，还会启动心跳线程。
 * 
 * @param handle 连接管理器句柄，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 启动成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 句柄为空指针
 *         - PROTOCOL_ERROR_ALREADY_CONNECTED: 连接已存在
 *         - PROTOCOL_ERROR_CONNECTION_FAILED: 发送STARTDT失败
 * 
 * @note 启动成功后，连接状态会变为CONNECTING，等待STARTDT确认
 * @warning 只有在DISCONNECTED状态下才能启动连接
 * @see protocol_connection_stop
 * @see protocol_connection_handle_apdu
 */
protocol_error_t protocol_connection_start(protocol_connection_handle_t handle) {
    LOG_DEBUG(LOG_MODULE_NAME, "函数入口: protocol_connection_start, handle=%p", handle);
    
    // 参数有效性检查
    if (handle == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "连接管理器句柄为空指针");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    protocol_connection_private_t* private_data = (protocol_connection_private_t*)handle;
    LOG_DEBUG(LOG_MODULE_NAME, "获取私有数据: %p", private_data);
    
    // 获取互斥锁保护共享数据
    LOG_DEBUG(LOG_MODULE_NAME, "获取互斥锁");
    pthread_mutex_lock(&private_data->mutex);
    
    // 检查当前连接状态
    LOG_DEBUG(LOG_MODULE_NAME, "当前连接状态: %s", 
              protocol_connection_get_state_name(private_data->current_state));
    
    if (private_data->current_state != CONNECTION_STATE_DISCONNECTED) {
        LOG_ERROR(LOG_MODULE_NAME, "连接已存在，当前状态: %s，无法启动新连接", 
                  protocol_connection_get_state_name(private_data->current_state));
        pthread_mutex_unlock(&private_data->mutex);
        return PROTOCOL_ERROR_ALREADY_CONNECTED;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "开始启动104协议连接，当前状态: DISCONNECTED");
    
    // 转换到连接中状态
    LOG_DEBUG(LOG_MODULE_NAME, "状态变化: %s -> %s", 
              protocol_connection_get_state_name(private_data->current_state),
              protocol_connection_get_state_name(CONNECTION_STATE_CONNECTING));
    protocol_connection_change_state(private_data, CONNECTION_STATE_CONNECTING);
    
    // 构建STARTDT请求APDU
    LOG_DEBUG(LOG_MODULE_NAME, "构建STARTDT请求APDU");
    apdu_t startdt_apdu;
    memset(&startdt_apdu, 0, sizeof(apdu_t));
    startdt_apdu.start = APDU_START_CHAR;                    // 启动字符 0x68
    startdt_apdu.length = APDU_MIN_LENGTH;                   // 最小长度 4
    startdt_apdu.control_field.control1 = U_FORMAT_STARTDT_ACT; // STARTDT激活
    
    LOG_DEBUG(LOG_MODULE_NAME, "STARTDT APDU构建完成: 启动字符=0x%02X, 长度=%d, 控制域=0x%02X", 
              startdt_apdu.start, startdt_apdu.length, startdt_apdu.control_field.control1);
    
    // 发送STARTDT请求
    protocol_error_t result = PROTOCOL_SUCCESS;
    if (private_data->send_callback) {
        LOG_DEBUG(LOG_MODULE_NAME, "调用发送回调函数发送STARTDT请求");
        result = private_data->send_callback(&startdt_apdu, private_data->send_user_data);
        LOG_DEBUG(LOG_MODULE_NAME, "STARTDT发送结果: %s", 
                  result == PROTOCOL_SUCCESS ? "成功" : "失败");
    } else {
        LOG_WARN(LOG_MODULE_NAME, "发送回调函数未设置，无法发送STARTDT请求");
        result = PROTOCOL_ERROR_CONNECTION_FAILED;
    }
    
    if (result == PROTOCOL_SUCCESS) {
        // 设置等待响应标志和事件类型
        private_data->waiting_for_response = true;
        private_data->pending_event = CONNECTION_EVENT_STARTDT_REQUEST;
        gettimeofday(&private_data->last_activity, NULL);
        
        // 更新统计信息
        private_data->stats.startdt_requests++;
        
        LOG_INFO(LOG_MODULE_NAME, "STARTDT请求发送成功，等待确认，超时时间: %dms", 
                 private_data->config.startdt_timeout);
        LOG_DEBUG(LOG_MODULE_NAME, "等待响应标志已设置，待处理事件: STARTDT_REQUEST");
    } else {
        // 发送失败，转换到错误状态
        LOG_ERROR(LOG_MODULE_NAME, "STARTDT请求发送失败，错误码: %d", result);
        protocol_connection_change_state(private_data, CONNECTION_STATE_ERROR);
        private_data->stats.errors++;
        
        LOG_INFO(LOG_MODULE_NAME, "连接启动失败，状态已转换为ERROR");
    }
    
    // 释放互斥锁
    pthread_mutex_unlock(&private_data->mutex);
    LOG_DEBUG(LOG_MODULE_NAME, "释放互斥锁");
    
    return result;
}

/**
 * @brief 停止连接
 * @details 停止104协议连接，发送STOPDT请求停止数据传输。该函数会检查当前连接状态，
 *          如果已经断开则直接返回成功。停止过程包括状态转换、停止心跳线程、
 *          构建STOPDT APDU、发送请求并设置等待响应标志。如果发送失败，会直接
 *          转换到断开状态。
 * 
 * @param handle 连接管理器句柄，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 停止成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 句柄为空指针
 *         - PROTOCOL_ERROR_CONNECTION_FAILED: 发送STOPDT失败
 * 
 * @note 停止成功后，连接状态会变为DISCONNECTING，等待STOPDT确认
 * @warning 此函数会停止心跳线程，请确保在合适的时机调用
 * @see protocol_connection_start
 * @see protocol_connection_handle_apdu
 */
protocol_error_t protocol_connection_stop(protocol_connection_handle_t handle) {
    LOG_DEBUG(LOG_MODULE_NAME, "函数入口: protocol_connection_stop, handle=%p", handle);
    
    // 参数有效性检查
    if (handle == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "连接管理器句柄为空指针");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    protocol_connection_private_t* private_data = (protocol_connection_private_t*)handle;
    LOG_DEBUG(LOG_MODULE_NAME, "获取私有数据: %p", private_data);
    
    // 获取互斥锁保护共享数据
    LOG_DEBUG(LOG_MODULE_NAME, "获取互斥锁");
    pthread_mutex_lock(&private_data->mutex);
    
    // 检查当前连接状态
    LOG_DEBUG(LOG_MODULE_NAME, "当前连接状态: %s", 
              protocol_connection_get_state_name(private_data->current_state));
    
    if (private_data->current_state == CONNECTION_STATE_DISCONNECTED) {
        LOG_INFO(LOG_MODULE_NAME, "连接已经断开，无需重复停止");
        pthread_mutex_unlock(&private_data->mutex);
        return PROTOCOL_SUCCESS; // 已经断开
    }
    
    LOG_INFO(LOG_MODULE_NAME, "开始停止104协议连接，当前状态: %s", 
             protocol_connection_get_state_name(private_data->current_state));
    
    // 转换到断开中状态
    LOG_DEBUG(LOG_MODULE_NAME, "状态变化: %s -> %s", 
              protocol_connection_get_state_name(private_data->current_state),
              protocol_connection_get_state_name(CONNECTION_STATE_DISCONNECTING));
    protocol_connection_change_state(private_data, CONNECTION_STATE_DISCONNECTING);
    
    // 停止心跳线程
    LOG_DEBUG(LOG_MODULE_NAME, "停止心跳线程");
    private_data->thread_running = false;
    private_data->running = false;
    
    // 构建STOPDT请求APDU
    LOG_DEBUG(LOG_MODULE_NAME, "构建STOPDT请求APDU");
    apdu_t stopdt_apdu;
    memset(&stopdt_apdu, 0, sizeof(apdu_t));
    stopdt_apdu.start = APDU_START_CHAR;                    // 启动字符 0x68
    stopdt_apdu.length = APDU_MIN_LENGTH;                   // 最小长度 4
    stopdt_apdu.control_field.control1 = U_FORMAT_STOPDT_ACT; // STOPDT激活
    
    LOG_DEBUG(LOG_MODULE_NAME, "STOPDT APDU构建完成: 启动字符=0x%02X, 长度=%d, 控制域=0x%02X", 
              stopdt_apdu.start, stopdt_apdu.length, stopdt_apdu.control_field.control1);
    
    // 发送STOPDT请求
    protocol_error_t result = PROTOCOL_SUCCESS;
    if (private_data->send_callback) {
        LOG_DEBUG(LOG_MODULE_NAME, "调用发送回调函数发送STOPDT请求");
        result = private_data->send_callback(&stopdt_apdu, private_data->send_user_data);
        LOG_DEBUG(LOG_MODULE_NAME, "STOPDT发送结果: %s", 
                  result == PROTOCOL_SUCCESS ? "成功" : "失败");
    } else {
        LOG_WARN(LOG_MODULE_NAME, "发送回调函数未设置，无法发送STOPDT请求");
        result = PROTOCOL_ERROR_CONNECTION_FAILED;
    }
    
    if (result == PROTOCOL_SUCCESS) {
        // 设置等待响应标志和事件类型
        private_data->waiting_for_response = true;
        private_data->pending_event = CONNECTION_EVENT_STOPDT_REQUEST;
        gettimeofday(&private_data->last_activity, NULL);
        
        // 更新统计信息
        private_data->stats.stopdt_requests++;
        
        LOG_INFO(LOG_MODULE_NAME, "STOPDT请求发送成功，等待确认，超时时间: %dms", 
                 private_data->config.stopdt_timeout);
        LOG_DEBUG(LOG_MODULE_NAME, "等待响应标志已设置，待处理事件: STOPDT_REQUEST");
    } else {
        // 发送失败，直接转换到断开状态
        LOG_ERROR(LOG_MODULE_NAME, "STOPDT请求发送失败，错误码: %d", result);
        protocol_connection_change_state(private_data, CONNECTION_STATE_DISCONNECTED);
        private_data->stats.errors++;
        
        LOG_INFO(LOG_MODULE_NAME, "连接停止失败，状态已转换为DISCONNECTED");
    }
    
    // 释放互斥锁
    pthread_mutex_unlock(&private_data->mutex);
    LOG_DEBUG(LOG_MODULE_NAME, "释放互斥锁");
    
    // 等待心跳线程结束
    if (private_data->heartbeat_thread) {
        LOG_DEBUG(LOG_MODULE_NAME, "等待心跳线程结束");
        pthread_join(private_data->heartbeat_thread, NULL);
        LOG_DEBUG(LOG_MODULE_NAME, "心跳线程已结束");
    }
    
    return result;
}

/**
 * @brief 发送测试帧
 * @details 发送TESTFR测试帧，用于连接保活和检测连接状态。该函数会检查当前连接状态，
 *          只有在已连接状态下才能发送测试帧。发送过程包括构建TESTFR APDU、
 *          发送请求并设置等待响应标志。测试帧用于维护连接的活跃性，防止连接超时。
 * 
 * @param handle 连接管理器句柄，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 发送成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 句柄为空指针
 *         - PROTOCOL_ERROR_NOT_CONNECTED: 连接未建立
 *         - PROTOCOL_ERROR_CONNECTION_FAILED: 发送失败
 * 
 * @note 测试帧发送成功后，会等待TESTFR确认
 * @warning 只有在CONNECTED状态下才能发送测试帧
 * @see protocol_connection_handle_apdu
 */
protocol_error_t protocol_connection_send_testfr(protocol_connection_handle_t handle) {
    LOG_DEBUG(LOG_MODULE_NAME, "函数入口: protocol_connection_send_testfr, handle=%p", handle);
    
    // 参数有效性检查
    if (handle == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "连接管理器句柄为空指针");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    protocol_connection_private_t* private_data = (protocol_connection_private_t*)handle;
    LOG_DEBUG(LOG_MODULE_NAME, "获取私有数据: %p", private_data);
    
    // 获取互斥锁保护共享数据
    LOG_DEBUG(LOG_MODULE_NAME, "获取互斥锁");
    pthread_mutex_lock(&private_data->mutex);
    
    // 检查当前连接状态
    LOG_DEBUG(LOG_MODULE_NAME, "当前连接状态: %s", 
              protocol_connection_get_state_name(private_data->current_state));
    
    if (private_data->current_state != CONNECTION_STATE_CONNECTED) {
        LOG_ERROR(LOG_MODULE_NAME, "连接未建立，当前状态: %s，无法发送测试帧", 
                  protocol_connection_get_state_name(private_data->current_state));
        pthread_mutex_unlock(&private_data->mutex);
        return PROTOCOL_ERROR_NOT_CONNECTED;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "开始发送TESTFR测试帧，当前状态: CONNECTED");
    
    // 构建TESTFR请求APDU
    LOG_DEBUG(LOG_MODULE_NAME, "构建TESTFR请求APDU");
    apdu_t testfr_apdu;
    memset(&testfr_apdu, 0, sizeof(apdu_t));
    testfr_apdu.start = APDU_START_CHAR;                    // 启动字符 0x68
    testfr_apdu.length = APDU_MIN_LENGTH;                   // 最小长度 4
    testfr_apdu.control_field.control1 = U_FORMAT_TESTFR_ACT; // TESTFR激活
    
    LOG_DEBUG(LOG_MODULE_NAME, "TESTFR APDU构建完成: 启动字符=0x%02X, 长度=%d, 控制域=0x%02X", 
              testfr_apdu.start, testfr_apdu.length, testfr_apdu.control_field.control1);
    
    // 发送TESTFR请求
    protocol_error_t result = PROTOCOL_SUCCESS;
    if (private_data->send_callback) {
        LOG_DEBUG(LOG_MODULE_NAME, "调用发送回调函数发送TESTFR请求");
        result = private_data->send_callback(&testfr_apdu, private_data->send_user_data);
        LOG_DEBUG(LOG_MODULE_NAME, "TESTFR发送结果: %s", 
                  result == PROTOCOL_SUCCESS ? "成功" : "失败");
    } else {
        LOG_WARN(LOG_MODULE_NAME, "发送回调函数未设置，无法发送TESTFR请求");
        result = PROTOCOL_ERROR_CONNECTION_FAILED;
    }
    
    if (result == PROTOCOL_SUCCESS) {
        // 设置等待响应标志和事件类型
        private_data->waiting_for_response = true;
        private_data->pending_event = CONNECTION_EVENT_TESTFR_REQUEST;
        gettimeofday(&private_data->last_activity, NULL);
        
        // 更新统计信息
        private_data->stats.testfr_requests++;
        
        LOG_INFO(LOG_MODULE_NAME, "TESTFR请求发送成功，等待确认，超时时间: %dms", 
                 private_data->config.testfr_timeout);
        LOG_DEBUG(LOG_MODULE_NAME, "等待响应标志已设置，待处理事件: TESTFR_REQUEST");
    } else {
        // 发送失败，更新错误统计
        LOG_ERROR(LOG_MODULE_NAME, "TESTFR请求发送失败，错误码: %d", result);
        private_data->stats.errors++;
        
        LOG_INFO(LOG_MODULE_NAME, "TESTFR发送失败，错误统计已更新");
    }
    
    // 释放互斥锁
    pthread_mutex_unlock(&private_data->mutex);
    LOG_DEBUG(LOG_MODULE_NAME, "释放互斥锁");
    
    return result;
}

/**
 * @brief 处理接收的APDU
 * @details 处理接收到的104协议APDU数据单元，主要处理U格式的控制帧。
 *          该函数会解析APDU类型，根据不同的U格式类型执行相应的处理逻辑，
 *          包括STARTDT、STOPDT、TESTFR的请求和确认处理。
 * 
 * @param handle 连接管理器句柄，不能为NULL
 * @param apdu 接收到的APDU数据单元，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 处理成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 参数为空指针
 * 
 * @note 该函数会更新最后活动时间，用于心跳超时检测
 * @warning 该函数是线程安全的，使用互斥锁保护共享数据
 * @see protocol_connection_start
 * @see protocol_connection_stop
 * @see protocol_connection_send_testfr
 */
protocol_error_t protocol_connection_handle_apdu(protocol_connection_handle_t handle, 
                                                const apdu_t* apdu) {
    LOG_DEBUG(LOG_MODULE_NAME, "函数入口: protocol_connection_handle_apdu, handle=%p, apdu=%p", handle, apdu);
    
    // 参数有效性检查
    if (handle == NULL || apdu == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "连接管理器句柄或APDU为空指针");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    protocol_connection_private_t* private_data = (protocol_connection_private_t*)handle;
    LOG_DEBUG(LOG_MODULE_NAME, "获取私有数据: %p", private_data);
    
    // 获取互斥锁保护共享数据
    LOG_DEBUG(LOG_MODULE_NAME, "获取互斥锁");
    pthread_mutex_lock(&private_data->mutex);
    
    // 更新最后活动时间，用于心跳超时检测
    gettimeofday(&private_data->last_activity, NULL);
    LOG_DEBUG(LOG_MODULE_NAME, "更新最后活动时间: %ld.%06ld", 
              private_data->last_activity.tv_sec, private_data->last_activity.tv_usec);
    
    // 检查是否是U格式APDU
    if (is_u_format_apdu(apdu)) {
        LOG_INFO(LOG_MODULE_NAME, "收到U格式APDU，启动字符=0x%02X, 长度=%d, 控制域=0x%02X", 
                 apdu->start, apdu->length, apdu->control_field.control1);
        
        // 解析U格式控制域
        u_format_type_t u_type = (u_format_type_t)apdu->control_field.control1;
        LOG_DEBUG(LOG_MODULE_NAME, "U格式类型: %d", u_type);
        
        switch (u_type) {
            case U_FORMAT_STARTDT_ACT:
                // 收到STARTDT请求，发送确认
                LOG_INFO(LOG_MODULE_NAME, "收到STARTDT激活请求，发送确认");
                protocol_connection_send_startdt_confirm(private_data);
                break;
                
            case U_FORMAT_STARTDT_CON:
                // 收到STARTDT确认
                LOG_INFO(LOG_MODULE_NAME, "收到STARTDT确认，当前等待响应: %s, 待处理事件: %d", 
                         private_data->waiting_for_response ? "是" : "否", private_data->pending_event);
                if (private_data->waiting_for_response && 
                    private_data->pending_event == CONNECTION_EVENT_STARTDT_REQUEST) {
                    private_data->waiting_for_response = false;
                    protocol_connection_change_state(private_data, CONNECTION_STATE_CONNECTED);
                    private_data->stats.startdt_confirms++;
                    
                    LOG_INFO(LOG_MODULE_NAME, "STARTDT确认处理完成，状态转换为CONNECTED");
                    
                    // 启动心跳线程
                    if (private_data->config.auto_heartbeat) {
                        LOG_DEBUG(LOG_MODULE_NAME, "配置了自动心跳，启动心跳线程");
                        protocol_connection_start_heartbeat(private_data);
                    }
                }
                break;
                
            case U_FORMAT_STOPDT_ACT:
                // 收到STOPDT请求，发送确认
                LOG_INFO(LOG_MODULE_NAME, "收到STOPDT激活请求，发送确认");
                protocol_connection_send_stopdt_confirm(private_data);
                break;
                
            case U_FORMAT_STOPDT_CON:
                // 收到STOPDT确认
                LOG_INFO(LOG_MODULE_NAME, "收到STOPDT确认，当前等待响应: %s, 待处理事件: %d", 
                         private_data->waiting_for_response ? "是" : "否", private_data->pending_event);
                if (private_data->waiting_for_response && 
                    private_data->pending_event == CONNECTION_EVENT_STOPDT_REQUEST) {
                    private_data->waiting_for_response = false;
                    protocol_connection_change_state(private_data, CONNECTION_STATE_DISCONNECTED);
                    private_data->stats.stopdt_confirms++;
                    
                    LOG_INFO(LOG_MODULE_NAME, "STOPDT确认处理完成，状态转换为DISCONNECTED");
                }
                break;
                
            case U_FORMAT_TESTFR_ACT:
                // 收到TESTFR请求，发送确认
                LOG_INFO(LOG_MODULE_NAME, "收到TESTFR激活请求，发送确认");
                protocol_connection_send_testfr_confirm(private_data);
                break;
                
            case U_FORMAT_TESTFR_CON:
                // 收到TESTFR确认
                LOG_INFO(LOG_MODULE_NAME, "收到TESTFR确认，当前等待响应: %s, 待处理事件: %d", 
                         private_data->waiting_for_response ? "是" : "否", private_data->pending_event);
                if (private_data->waiting_for_response && 
                    private_data->pending_event == CONNECTION_EVENT_TESTFR_REQUEST) {
                    private_data->waiting_for_response = false;
                    private_data->stats.testfr_confirms++;
                    
                    LOG_INFO(LOG_MODULE_NAME, "TESTFR确认处理完成");
                }
                break;
                
            default:
                LOG_WARN(LOG_MODULE_NAME, "收到未知的U格式类型: %d", u_type);
                break;
        }
    } else {
        LOG_DEBUG(LOG_MODULE_NAME, "收到非U格式APDU，启动字符=0x%02X, 长度=%d", 
                  apdu->start, apdu->length);
    }
    
    // 释放互斥锁
    pthread_mutex_unlock(&private_data->mutex);
    LOG_DEBUG(LOG_MODULE_NAME, "释放互斥锁");
    
    return PROTOCOL_SUCCESS;
}

/* ==================== 状态查询函数实现 ==================== */

/**
 * @brief 获取连接状态
 * @details 获取当前连接管理器的连接状态。该函数是线程安全的，
 *          使用互斥锁保护共享数据的访问。
 * 
 * @param handle 连接管理器句柄，不能为NULL
 * 
 * @return 连接状态
 *         - CONNECTION_STATE_DISCONNECTED: 已断开
 *         - CONNECTION_STATE_CONNECTING: 连接中
 *         - CONNECTION_STATE_CONNECTED: 已连接
 *         - CONNECTION_STATE_DISCONNECTING: 断开中
 *         - CONNECTION_STATE_ERROR: 错误状态
 *         - 如果句柄为NULL，返回CONNECTION_STATE_ERROR
 * 
 * @note 该函数是线程安全的
 * @see protocol_connection_is_connected
 */
connection_state_t protocol_connection_get_state(protocol_connection_handle_t handle) {
    LOG_DEBUG(LOG_MODULE_NAME, "函数入口: protocol_connection_get_state, handle=%p", handle);
    
    if (handle == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "连接管理器句柄为空指针");
        return CONNECTION_STATE_ERROR;
    }
    
    protocol_connection_private_t* private_data = (protocol_connection_private_t*)handle;
    
    pthread_mutex_lock(&private_data->mutex);
    connection_state_t state = private_data->current_state;
    pthread_mutex_unlock(&private_data->mutex);
    
    LOG_DEBUG(LOG_MODULE_NAME, "获取连接状态: %s", protocol_connection_get_state_name(state));
    
    return state;
}

/**
 * @brief 检查是否已连接
 * @details 检查连接管理器是否处于已连接状态。这是一个便捷函数，
 *          用于快速判断连接状态。
 * 
 * @param handle 连接管理器句柄，不能为NULL
 * 
 * @return 连接状态
 *         - true: 已连接
 *         - false: 未连接或句柄为NULL
 * 
 * @note 该函数内部调用protocol_connection_get_state()
 * @see protocol_connection_get_state
 */
bool protocol_connection_is_connected(protocol_connection_handle_t handle) {
    LOG_DEBUG(LOG_MODULE_NAME, "函数入口: protocol_connection_is_connected, handle=%p", handle);
    
    connection_state_t state = protocol_connection_get_state(handle);
    bool is_connected = (state == CONNECTION_STATE_CONNECTED);
    
    LOG_INFO(LOG_MODULE_NAME, "连接状态检查: %s", is_connected ? "已连接" : "未连接");
    
    return is_connected;
}

/**
 * @brief 获取连接统计信息
 * @details 获取连接管理器的统计信息，包括各种操作的计数和状态。
 *          该函数是线程安全的，使用互斥锁保护共享数据的访问。
 * 
 * @param handle 连接管理器句柄，不能为NULL
 * @param stats 统计信息输出缓冲区，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 获取成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 参数为空指针
 * 
 * @note 该函数是线程安全的
 * @see connection_stats_t
 */
protocol_error_t protocol_connection_get_stats(protocol_connection_handle_t handle, 
                                             connection_stats_t* stats) {
    LOG_DEBUG(LOG_MODULE_NAME, "函数入口: protocol_connection_get_stats, handle=%p, stats=%p", handle, stats);
    
    if (handle == NULL || stats == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "连接管理器句柄或统计信息缓冲区为空指针");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    protocol_connection_private_t* private_data = (protocol_connection_private_t*)handle;
    
    pthread_mutex_lock(&private_data->mutex);
    memcpy(stats, &private_data->stats, sizeof(connection_stats_t));
    pthread_mutex_unlock(&private_data->mutex);
    
    LOG_INFO(LOG_MODULE_NAME, "获取连接统计信息成功: STARTDT请求=%d, STARTDT确认=%d, STOPDT请求=%d, STOPDT确认=%d, TESTFR请求=%d, TESTFR确认=%d, 错误=%d", 
             stats->startdt_requests, stats->startdt_confirms, stats->stopdt_requests, 
             stats->stopdt_confirms, stats->testfr_requests, stats->testfr_confirms, stats->errors);
    
    return PROTOCOL_SUCCESS;
}

/* ==================== 回调设置函数实现 ==================== */

/**
 * @brief 设置连接状态回调函数
 * @details 设置连接状态变化时的回调函数。当连接状态发生变化时，
 *          系统会自动调用此回调函数通知应用程序。回调函数会在状态
 *          变化后立即被调用，应用程序可以在此函数中处理状态变化事件。
 * 
 * @param handle 连接管理器句柄，不能为NULL
 * @param callback 状态变化回调函数指针，可以为NULL（表示取消回调）
 * @param user_data 用户数据指针，会传递给回调函数，可以为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 设置成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 句柄为空指针
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 如果callback为NULL，则取消状态回调
 * @warning 回调函数应该尽快返回，避免阻塞连接管理器
 * @see connection_state_callback_t
 * @see protocol_connection_set_event_callback
 * @see protocol_connection_set_send_callback
 */
protocol_error_t protocol_connection_set_state_callback(protocol_connection_handle_t handle, 
                                                       connection_state_callback_t callback, 
                                                       void* user_data) {
    LOG_DEBUG(LOG_MODULE_NAME, "函数入口: protocol_connection_set_state_callback, handle=%p, callback=%p, user_data=%p", 
              handle, callback, user_data);
    
    if (handle == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "连接管理器句柄为空指针");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    protocol_connection_private_t* private_data = (protocol_connection_private_t*)handle;
    
    pthread_mutex_lock(&private_data->mutex);
    private_data->state_callback = callback;
    private_data->state_user_data = user_data;
    pthread_mutex_unlock(&private_data->mutex);
    
    LOG_INFO(LOG_MODULE_NAME, "连接状态回调函数设置成功，回调函数: %s", 
             callback ? "已设置" : "已取消");
    
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 设置连接事件回调函数
 * @details 设置连接事件发生时的回调函数。当连接管理器检测到特定事件
 *          （如STARTDT请求、STOPDT确认、TESTFR超时等）时，系统会自动
 *          调用此回调函数通知应用程序。应用程序可以在此函数中处理各种
 *          连接事件，实现自定义的事件处理逻辑。
 * 
 * @param handle 连接管理器句柄，不能为NULL
 * @param callback 事件处理回调函数指针，可以为NULL（表示取消回调）
 * @param user_data 用户数据指针，会传递给回调函数，可以为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 设置成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 句柄为空指针
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 如果callback为NULL，则取消事件回调
 * @warning 回调函数应该尽快返回，避免阻塞连接管理器
 * @see connection_event_callback_t
 * @see protocol_connection_set_state_callback
 * @see protocol_connection_set_send_callback
 */
protocol_error_t protocol_connection_set_event_callback(protocol_connection_handle_t handle, 
                                                       connection_event_callback_t callback, 
                                                       void* user_data) {
    LOG_DEBUG(LOG_MODULE_NAME, "函数入口: protocol_connection_set_event_callback, handle=%p, callback=%p, user_data=%p", 
              handle, callback, user_data);
    
    if (handle == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "连接管理器句柄为空指针");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    protocol_connection_private_t* private_data = (protocol_connection_private_t*)handle;
    
    pthread_mutex_lock(&private_data->mutex);
    private_data->event_callback = callback;
    private_data->event_user_data = user_data;
    pthread_mutex_unlock(&private_data->mutex);
    
    LOG_INFO(LOG_MODULE_NAME, "连接事件回调函数设置成功，回调函数: %s", 
             callback ? "已设置" : "已取消");
    
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 设置APDU发送回调函数
 * @details 设置APDU数据发送时的回调函数。当连接管理器需要发送APDU数据
 *          （如STARTDT、STOPDT、TESTFR等控制帧）时，系统会调用此回调函数
 *          将APDU数据传递给底层传输层进行实际发送。应用程序需要在此回调
 *          函数中实现具体的网络发送逻辑。
 * 
 * @param handle 连接管理器句柄，不能为NULL
 * @param callback APDU发送回调函数指针，不能为NULL（连接管理器需要此回调来发送数据）
 * @param user_data 用户数据指针，会传递给回调函数，可以为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 设置成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 句柄为空指针
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note send_callback不能为NULL，连接管理器依赖此回调发送APDU数据
 * @warning 回调函数应该尽快返回，避免阻塞连接管理器
 * @see connection_send_callback_t
 * @see protocol_connection_set_state_callback
 * @see protocol_connection_set_event_callback
 */
protocol_error_t protocol_connection_set_send_callback(protocol_connection_handle_t handle, 
                                                      connection_send_callback_t callback, 
                                                      void* user_data) {
    LOG_DEBUG(LOG_MODULE_NAME, "函数入口: protocol_connection_set_send_callback, handle=%p, callback=%p, user_data=%p", 
              handle, callback, user_data);
    
    if (handle == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "连接管理器句柄为空指针");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    protocol_connection_private_t* private_data = (protocol_connection_private_t*)handle;
    
    pthread_mutex_lock(&private_data->mutex);
    private_data->send_callback = callback;
    private_data->send_user_data = user_data;
    pthread_mutex_unlock(&private_data->mutex);
    
    LOG_INFO(LOG_MODULE_NAME, "APDU发送回调函数设置成功，回调函数: %s", 
             callback ? "已设置" : "已取消");
    
    return PROTOCOL_SUCCESS;
}

/* ==================== 配置管理函数实现 ==================== */

/**
 * @brief 更新连接配置参数
 * @details 更新连接管理器的配置参数，包括超时时间、重试次数、心跳间隔等。
 *          该函数会验证新配置的有效性，只有通过验证的配置才会被应用。
 *          配置更新是原子操作，使用互斥锁保护，确保配置的一致性。
 * 
 * @param handle 连接管理器句柄，不能为NULL
 * @param config 新的连接配置参数，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 更新成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 参数为空指针
 *         - PROTOCOL_ERROR_INVALID_PARAM: 配置参数无效
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 配置更新会立即生效，影响后续的连接操作
 * @warning 配置更新不会影响当前正在进行的连接操作
 * @see connection_config_t
 * @see protocol_connection_validate_config
 * @see protocol_connection_get_config
 */
protocol_error_t protocol_connection_update_config(protocol_connection_handle_t handle, 
                                                  const connection_config_t* config) {
    LOG_DEBUG(LOG_MODULE_NAME, "函数入口: protocol_connection_update_config, handle=%p, config=%p", handle, config);
    
    if (handle == NULL || config == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "连接管理器句柄或配置参数为空指针");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "开始更新连接配置: STARTDT超时=%dms, STOPDT超时=%dms, TESTFR超时=%dms, 心跳间隔=%dms", 
             config->startdt_timeout, config->stopdt_timeout, config->testfr_timeout, config->heartbeat_interval);
    
    // 验证配置参数的有效性
    protocol_error_t validation_result = protocol_connection_validate_config(config);
    if (validation_result != PROTOCOL_SUCCESS) {
        LOG_ERROR(LOG_MODULE_NAME, "连接配置验证失败，错误码: %d", validation_result);
        return PROTOCOL_ERROR_INVALID_PARAM;
    }
    
    protocol_connection_private_t* private_data = (protocol_connection_private_t*)handle;
    
    pthread_mutex_lock(&private_data->mutex);
    memcpy(&private_data->config, config, sizeof(connection_config_t));
    pthread_mutex_unlock(&private_data->mutex);
    
    LOG_INFO(LOG_MODULE_NAME, "连接配置更新成功");
    
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 获取连接配置参数
 * @details 获取连接管理器的当前配置参数，包括超时时间、重试次数、心跳间隔等。
 *          该函数会复制当前的配置参数到提供的缓冲区中，应用程序可以查看
 *          当前的配置设置。配置获取是原子操作，使用互斥锁保护，确保数据的一致性。
 * 
 * @param handle 连接管理器句柄，不能为NULL
 * @param config 配置参数输出缓冲区，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 获取成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 参数为空指针
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 获取的配置是当前生效的配置参数
 * @see connection_config_t
 * @see protocol_connection_update_config
 * @see protocol_connection_validate_config
 */
protocol_error_t protocol_connection_get_config(protocol_connection_handle_t handle, 
                                               connection_config_t* config) {
    LOG_DEBUG(LOG_MODULE_NAME, "函数入口: protocol_connection_get_config, handle=%p, config=%p", handle, config);
    
    if (handle == NULL || config == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "连接管理器句柄或配置缓冲区为空指针");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    protocol_connection_private_t* private_data = (protocol_connection_private_t*)handle;
    
    pthread_mutex_lock(&private_data->mutex);
    memcpy(config, &private_data->config, sizeof(connection_config_t));
    pthread_mutex_unlock(&private_data->mutex);
    
    LOG_INFO(LOG_MODULE_NAME, "获取连接配置成功: STARTDT超时=%dms, STOPDT超时=%dms, TESTFR超时=%dms, 心跳间隔=%dms, 最大重试=%d", 
             config->startdt_timeout, config->stopdt_timeout, config->testfr_timeout, 
             config->heartbeat_interval, config->max_retry_count);
    
    return PROTOCOL_SUCCESS;
}

/* ==================== 辅助函数实现 ==================== */

/**
 * @brief 获取连接状态名称字符串
 * @details 将连接状态枚举值转换为对应的字符串名称，用于日志记录和调试。
 *          该函数返回静态字符串数组中的对应项，返回的字符串指针在程序
 *          运行期间保持有效，不需要释放内存。
 * 
 * @param state 连接状态枚举值
 * 
 * @return 状态名称字符串
 *         - "DISCONNECTED": 已断开状态
 *         - "CONNECTING": 连接中状态
 *         - "CONNECTED": 已连接状态
 *         - "DISCONNECTING": 断开中状态
 *         - "ERROR": 错误状态
 *         - "UNKNOWN": 未知状态（当state值无效时）
 * 
 * @note 返回的字符串指针是静态的，不需要释放内存
 * @note 该函数是线程安全的，只读取静态数据
 * @see connection_state_t
 * @see protocol_connection_get_event_name
 */
const char* protocol_connection_get_state_name(connection_state_t state) {
    static const char* state_names[] = {
        "DISCONNECTED",    // 已断开状态
        "CONNECTING",      // 连接中状态
        "CONNECTED",       // 已连接状态
        "DISCONNECTING",   // 断开中状态
        "ERROR"            // 错误状态
    };
    
    if (state >= sizeof(state_names) / sizeof(state_names[0])) {
        return "UNKNOWN";
    }
    
    return state_names[state];
}

/**
 * @brief 获取连接事件名称字符串
 * @details 将连接事件枚举值转换为对应的字符串名称，用于日志记录和调试。
 *          该函数返回静态字符串数组中的对应项，返回的字符串指针在程序
 *          运行期间保持有效，不需要释放内存。
 * 
 * @param event 连接事件枚举值
 * 
 * @return 事件名称字符串
 *         - "STARTDT_REQUEST": STARTDT请求事件
 *         - "STARTDT_CONFIRM": STARTDT确认事件
 *         - "STOPDT_REQUEST": STOPDT请求事件
 *         - "STOPDT_CONFIRM": STOPDT确认事件
 *         - "TESTFR_REQUEST": TESTFR请求事件
 *         - "TESTFR_CONFIRM": TESTFR确认事件
 *         - "TIMEOUT": 超时事件
 *         - "ERROR": 错误事件
 *         - "UNKNOWN": 未知事件（当event值无效时）
 * 
 * @note 返回的字符串指针是静态的，不需要释放内存
 * @note 该函数是线程安全的，只读取静态数据
 * @see connection_event_t
 * @see protocol_connection_get_state_name
 */
const char* protocol_connection_get_event_name(connection_event_t event) {
    static const char* event_names[] = {
        "STARTDT_REQUEST",  // STARTDT请求事件
        "STARTDT_CONFIRM",  // STARTDT确认事件
        "STOPDT_REQUEST",   // STOPDT请求事件
        "STOPDT_CONFIRM",   // STOPDT确认事件
        "TESTFR_REQUEST",   // TESTFR请求事件
        "TESTFR_CONFIRM",   // TESTFR确认事件
        "TIMEOUT",          // 超时事件
        "ERROR"             // 错误事件
    };
    
    if (event >= sizeof(event_names) / sizeof(event_names[0])) {
        return "UNKNOWN";
    }
    
    return event_names[event];
}

/**
 * @brief 验证连接配置参数的有效性
 * @details 验证连接配置参数是否符合104协议的要求和系统限制。
 *          该函数会检查所有必要的配置参数，确保它们的值在有效范围内。
 *          验证包括超时时间、重试次数等关键参数的合理性检查。
 * 
 * @param config 待验证的连接配置参数，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 配置验证通过
 *         - PROTOCOL_ERROR_NULL_POINTER: 配置参数为空指针
 *         - PROTOCOL_ERROR_INVALID_PARAM: 配置参数无效
 * 
 * @note 该函数是线程安全的，只读取配置数据
 * @note 验证规则：
 *       - 所有超时时间必须大于0
 *       - 最大重试次数必须大于0
 *       - 心跳间隔必须大于0（如果启用自动心跳）
 * @see connection_config_t
 * @see protocol_connection_update_config
 * @see protocol_connection_get_config
 */
protocol_error_t protocol_connection_validate_config(const connection_config_t* config) {
    LOG_DEBUG(LOG_MODULE_NAME, "函数入口: protocol_connection_validate_config, config=%p", config);
    
    if (config == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "连接配置参数为空指针");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    LOG_DEBUG(LOG_MODULE_NAME, "开始验证连接配置: STARTDT超时=%dms, STOPDT超时=%dms, TESTFR超时=%dms, 最大重试=%d", 
              config->startdt_timeout, config->stopdt_timeout, config->testfr_timeout, config->max_retry_count);
    
    // 验证超时时间参数
    if (config->startdt_timeout == 0 || config->stopdt_timeout == 0 || 
        config->testfr_timeout == 0) {
        LOG_ERROR(LOG_MODULE_NAME, "超时时间参数无效: STARTDT=%dms, STOPDT=%dms, TESTFR=%dms", 
                  config->startdt_timeout, config->stopdt_timeout, config->testfr_timeout);
        return PROTOCOL_ERROR_INVALID_PARAM;
    }
    
    // 验证重试次数参数
    if (config->max_retry_count == 0) {
        LOG_ERROR(LOG_MODULE_NAME, "最大重试次数无效: %d", config->max_retry_count);
        return PROTOCOL_ERROR_INVALID_PARAM;
    }
    
    // 验证心跳间隔参数（如果启用自动心跳）
    if (config->auto_heartbeat && config->heartbeat_interval == 0) {
        LOG_ERROR(LOG_MODULE_NAME, "启用自动心跳但心跳间隔为0: %dms", config->heartbeat_interval);
        return PROTOCOL_ERROR_INVALID_PARAM;
    }
    
    LOG_INFO(LOG_MODULE_NAME, "连接配置验证通过");
    
    return PROTOCOL_SUCCESS;
}

/**
 * @brief 重置连接统计信息
 * @details 将连接管理器的所有统计信息重置为零。该函数会清空所有计数器，
 *          包括STARTDT、STOPDT、TESTFR的请求和确认次数，以及错误计数等。
 *          重置操作是原子操作，使用互斥锁保护，确保数据的一致性。
 * 
 * @param handle 连接管理器句柄，不能为NULL
 * 
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 重置成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 句柄为空指针
 * 
 * @note 该函数是线程安全的，使用互斥锁保护共享数据
 * @note 重置后所有统计计数器都将变为0
 * @warning 重置操作不可逆，请谨慎使用
 * @see connection_stats_t
 * @see protocol_connection_get_stats
 */
protocol_error_t protocol_connection_reset_stats(protocol_connection_handle_t handle) {
    LOG_DEBUG(LOG_MODULE_NAME, "函数入口: protocol_connection_reset_stats, handle=%p", handle);
    
    if (handle == NULL) {
        LOG_ERROR(LOG_MODULE_NAME, "连接管理器句柄为空指针");
        return PROTOCOL_ERROR_NULL_POINTER;
    }
    
    protocol_connection_private_t* private_data = (protocol_connection_private_t*)handle;
    
    pthread_mutex_lock(&private_data->mutex);
    memset(&private_data->stats, 0, sizeof(connection_stats_t));
    pthread_mutex_unlock(&private_data->mutex);
    
    LOG_INFO(LOG_MODULE_NAME, "连接统计信息重置成功，所有计数器已清零");
    
    return PROTOCOL_SUCCESS;
}

/* ==================== 内部函数实现 ==================== */

/**
 * @brief 连接状态变化处理函数
 * @details 处理连接状态的内部变化，更新当前状态并触发状态变化回调。
 *          该函数是内部函数，用于统一管理状态变化逻辑，确保状态变化
 *          的一致性和回调函数的正确调用。只有在状态确实发生变化时
 *          才会执行状态更新和回调触发。
 * 
 * @param private_data 连接管理器私有数据指针，不能为NULL
 * @param new_state 新的连接状态
 * 
 * @note 该函数是内部函数，不进行参数有效性检查
 * @note 该函数不是线程安全的，调用者需要确保线程安全
 * @note 如果状态没有变化，函数会直接返回，不执行任何操作
 * @note 状态变化后会立即触发状态回调函数（如果已设置）
 * @see connection_state_t
 * @see connection_state_callback_t
 */
static void protocol_connection_change_state(protocol_connection_private_t* private_data, 
                                           connection_state_t new_state) {
    LOG_DEBUG(LOG_MODULE_NAME, "内部函数: protocol_connection_change_state, 当前状态: %s, 新状态: %s", 
              protocol_connection_get_state_name(private_data->current_state),
              protocol_connection_get_state_name(new_state));
    
    if (private_data->current_state == new_state) {
        LOG_DEBUG(LOG_MODULE_NAME, "状态没有变化，直接返回");
        return; // 状态没有变化
    }
    
    connection_state_t old_state = private_data->current_state;
    private_data->current_state = new_state;
    
    LOG_INFO(LOG_MODULE_NAME, "连接状态变化: %s -> %s", 
             protocol_connection_get_state_name(old_state),
             protocol_connection_get_state_name(new_state));
    
    // 调用状态变化回调
    if (private_data->state_callback) {
        LOG_DEBUG(LOG_MODULE_NAME, "触发状态变化回调函数");
        private_data->state_callback(old_state, new_state, private_data->state_user_data);
    } else {
        LOG_DEBUG(LOG_MODULE_NAME, "状态回调函数未设置，跳过回调");
    }
}

/**
 * @brief 发送STARTDT确认帧
 * @details 构建并发送STARTDT确认APDU，用于响应对方发送的STARTDT激活请求。
 *          该函数是内部函数，用于处理U格式的STARTDT确认帧发送。确认帧
 *          的格式严格按照104协议标准构建，包含启动字符、长度和控制域。
 * 
 * @param private_data 连接管理器私有数据指针，不能为NULL
 * 
 * @note 该函数是内部函数，不进行参数有效性检查
 * @note 该函数不是线程安全的，调用者需要确保线程安全
 * @note 如果发送回调函数未设置，函数会静默返回
 * @note STARTDT确认帧格式：启动字符(0x68) + 长度(4) + 控制域(U_FORMAT_STARTDT_CON)
 * @see U_FORMAT_STARTDT_CON
 * @see protocol_connection_send_stopdt_confirm
 * @see protocol_connection_send_testfr_confirm
 */
static void protocol_connection_send_startdt_confirm(protocol_connection_private_t* private_data) {
    LOG_DEBUG(LOG_MODULE_NAME, "内部函数: protocol_connection_send_startdt_confirm");
    
    apdu_t startdt_con_apdu;
    memset(&startdt_con_apdu, 0, sizeof(apdu_t));
    
    // 构建STARTDT确认APDU
    startdt_con_apdu.start = APDU_START_CHAR;                    // 启动字符 0x68
    startdt_con_apdu.length = APDU_MIN_LENGTH;                   // 最小长度 4
    startdt_con_apdu.control_field.control1 = U_FORMAT_STARTDT_CON; // STARTDT确认
    
    LOG_DEBUG(LOG_MODULE_NAME, "构建STARTDT确认APDU: 启动字符=0x%02X, 长度=%d, 控制域=0x%02X", 
              startdt_con_apdu.start, startdt_con_apdu.length, startdt_con_apdu.control_field.control1);
    
    if (private_data->send_callback) {
        LOG_INFO(LOG_MODULE_NAME, "发送STARTDT确认帧");
        private_data->send_callback(&startdt_con_apdu, private_data->send_user_data);
    } else {
        LOG_WARN(LOG_MODULE_NAME, "发送回调函数未设置，无法发送STARTDT确认");
    }
}

/**
 * @brief 发送STOPDT确认帧
 * @details 构建并发送STOPDT确认APDU，用于响应对方发送的STOPDT激活请求。
 *          该函数是内部函数，用于处理U格式的STOPDT确认帧发送。确认帧
 *          的格式严格按照104协议标准构建，包含启动字符、长度和控制域。
 * 
 * @param private_data 连接管理器私有数据指针，不能为NULL
 * 
 * @note 该函数是内部函数，不进行参数有效性检查
 * @note 该函数不是线程安全的，调用者需要确保线程安全
 * @note 如果发送回调函数未设置，函数会静默返回
 * @note STOPDT确认帧格式：启动字符(0x68) + 长度(4) + 控制域(U_FORMAT_STOPDT_CON)
 * @see U_FORMAT_STOPDT_CON
 * @see protocol_connection_send_startdt_confirm
 * @see protocol_connection_send_testfr_confirm
 */
static void protocol_connection_send_stopdt_confirm(protocol_connection_private_t* private_data) {
    LOG_DEBUG(LOG_MODULE_NAME, "内部函数: protocol_connection_send_stopdt_confirm");
    
    apdu_t stopdt_con_apdu;
    memset(&stopdt_con_apdu, 0, sizeof(apdu_t));
    
    // 构建STOPDT确认APDU
    stopdt_con_apdu.start = APDU_START_CHAR;                    // 启动字符 0x68
    stopdt_con_apdu.length = APDU_MIN_LENGTH;                   // 最小长度 4
    stopdt_con_apdu.control_field.control1 = U_FORMAT_STOPDT_CON; // STOPDT确认
    
    LOG_DEBUG(LOG_MODULE_NAME, "构建STOPDT确认APDU: 启动字符=0x%02X, 长度=%d, 控制域=0x%02X", 
              stopdt_con_apdu.start, stopdt_con_apdu.length, stopdt_con_apdu.control_field.control1);
    
    if (private_data->send_callback) {
        LOG_INFO(LOG_MODULE_NAME, "发送STOPDT确认帧");
        private_data->send_callback(&stopdt_con_apdu, private_data->send_user_data);
    } else {
        LOG_WARN(LOG_MODULE_NAME, "发送回调函数未设置，无法发送STOPDT确认");
    }
}

/**
 * @brief 发送TESTFR确认帧
 * @details 构建并发送TESTFR确认APDU，用于响应对方发送的TESTFR激活请求。
 *          该函数是内部函数，用于处理U格式的TESTFR确认帧发送。确认帧
 *          的格式严格按照104协议标准构建，包含启动字符、长度和控制域。
 * 
 * @param private_data 连接管理器私有数据指针，不能为NULL
 * 
 * @note 该函数是内部函数，不进行参数有效性检查
 * @note 该函数不是线程安全的，调用者需要确保线程安全
 * @note 如果发送回调函数未设置，函数会静默返回
 * @note TESTFR确认帧格式：启动字符(0x68) + 长度(4) + 控制域(U_FORMAT_TESTFR_CON)
 * @see U_FORMAT_TESTFR_CON
 * @see protocol_connection_send_startdt_confirm
 * @see protocol_connection_send_stopdt_confirm
 */
static void protocol_connection_send_testfr_confirm(protocol_connection_private_t* private_data) {
    LOG_DEBUG(LOG_MODULE_NAME, "内部函数: protocol_connection_send_testfr_confirm");
    
    apdu_t testfr_con_apdu;
    memset(&testfr_con_apdu, 0, sizeof(apdu_t));
    
    // 构建TESTFR确认APDU
    testfr_con_apdu.start = APDU_START_CHAR;                    // 启动字符 0x68
    testfr_con_apdu.length = APDU_MIN_LENGTH;                   // 最小长度 4
    testfr_con_apdu.control_field.control1 = U_FORMAT_TESTFR_CON; // TESTFR确认
    
    LOG_DEBUG(LOG_MODULE_NAME, "构建TESTFR确认APDU: 启动字符=0x%02X, 长度=%d, 控制域=0x%02X", 
              testfr_con_apdu.start, testfr_con_apdu.length, testfr_con_apdu.control_field.control1);
    
    if (private_data->send_callback) {
        LOG_INFO(LOG_MODULE_NAME, "发送TESTFR确认帧");
        private_data->send_callback(&testfr_con_apdu, private_data->send_user_data);
    } else {
        LOG_WARN(LOG_MODULE_NAME, "发送回调函数未设置，无法发送TESTFR确认");
    }
}

/**
 * @brief 启动心跳线程
 * @details 启动心跳监控线程，用于定期发送TESTFR测试帧以维护连接活跃性。
 *          该函数是内部函数，只有在配置了自动心跳且心跳间隔大于0时才会
 *          启动心跳线程。线程启动失败时会自动清理相关标志位。
 * 
 * @param private_data 连接管理器私有数据指针，不能为NULL
 * 
 * @note 该函数是内部函数，不进行参数有效性检查
 * @note 该函数不是线程安全的，调用者需要确保线程安全
 * @note 只有在auto_heartbeat为true且heartbeat_interval > 0时才会启动线程
 * @note 线程启动失败时会自动重置thread_running和running标志
 * @note 心跳线程会定期检查连接活跃性并发送TESTFR帧
 * @see protocol_connection_heartbeat_thread
 * @see protocol_connection_send_testfr
 */
static void protocol_connection_start_heartbeat(protocol_connection_private_t* private_data) {
    LOG_DEBUG(LOG_MODULE_NAME, "内部函数: protocol_connection_start_heartbeat, 自动心跳=%s, 心跳间隔=%dms", 
              private_data->config.auto_heartbeat ? "启用" : "禁用", private_data->config.heartbeat_interval);
    
    if (private_data->config.auto_heartbeat && private_data->config.heartbeat_interval > 0) {
        LOG_INFO(LOG_MODULE_NAME, "启动心跳线程，心跳间隔: %dms", private_data->config.heartbeat_interval);
        
        private_data->thread_running = true;
        private_data->running = true;
        
        int thread_result = pthread_create(&private_data->heartbeat_thread, NULL, 
                                         (void*(*)(void*))protocol_connection_heartbeat_thread, private_data);
        if (thread_result != 0) {
            LOG_ERROR(LOG_MODULE_NAME, "心跳线程创建失败，错误码: %d", thread_result);
            private_data->thread_running = false;
            private_data->running = false;
        } else {
            LOG_INFO(LOG_MODULE_NAME, "心跳线程启动成功");
        }
    } else {
        LOG_DEBUG(LOG_MODULE_NAME, "未启用自动心跳或心跳间隔为0，跳过心跳线程启动");
    }
}

/**
 * @brief 心跳监控线程函数
 * @details 心跳监控线程的主函数，用于定期检查连接活跃性并发送TESTFR测试帧。
 *          该线程会持续运行直到thread_running或running标志被设置为false。
 *          线程会定期检查自上次活动以来的时间间隔，如果超过配置的心跳间隔，
 *          就会发送TESTFR测试帧来维护连接的活跃性。
 * 
 * @param arg 线程参数，指向protocol_connection_private_t结构体的指针
 * 
 * @return 线程返回值，始终返回NULL
 * 
 * @note 该函数是内部线程函数，不进行参数有效性检查
 * @note 线程会持续运行直到收到停止信号
 * @note 线程会定期休眠1ms以避免过度占用CPU资源
 * @note 心跳间隔基于last_activity时间戳计算
 * @note 发送TESTFR时会调用公共接口函数
 * @see protocol_connection_start_heartbeat
 * @see protocol_connection_send_testfr
 * @see protocol_connection_private_t
 */
static void* protocol_connection_heartbeat_thread(void* arg) {
    protocol_connection_private_t* private_data = (protocol_connection_private_t*)arg;
    
    LOG_INFO(LOG_MODULE_NAME, "心跳线程启动，心跳间隔: %dms", private_data->config.heartbeat_interval);
    
    while (private_data->thread_running && private_data->running) {
        // 检查是否需要发送心跳
        struct timeval current_time;
        gettimeofday(&current_time, NULL);
        
        // 计算自上次活动以来的时间间隔（毫秒）
        long elapsed_ms = (current_time.tv_sec - private_data->last_activity.tv_sec) * 1000 +
                         (current_time.tv_usec - private_data->last_activity.tv_usec) / 1000;
        
        LOG_DEBUG(LOG_MODULE_NAME, "心跳检查: 已过去时间=%ldms, 心跳间隔=%dms", 
                  elapsed_ms, private_data->config.heartbeat_interval);
        
        if (elapsed_ms >= private_data->config.heartbeat_interval) {
            // 发送测试帧
            LOG_DEBUG(LOG_MODULE_NAME, "达到心跳间隔，发送TESTFR测试帧");
            protocol_connection_send_testfr((protocol_connection_handle_t)private_data);
        }
        
        // 短暂休眠，避免过度占用CPU资源
        struct timespec ts = {0, 1000000}; // 1ms
        nanosleep(&ts, NULL);
    }
    
    LOG_INFO(LOG_MODULE_NAME, "心跳线程结束");
    return NULL;
}
